DragItem Class
Used to transfer data being dragged by the user.
More information available in parent classes: Object
Notes
When the user wishes to drag some data from a window or Control, a new DragItem object must be created to hold that data in order to transfer it to the object the data will be dropped on. REALbasic implements true drag and drop -- which means that the recipient of the data can be anything that supports drag and drop and supports the kind of data being dragged. For example, text can be dragged to the desktop to create a text clipping file or any application that accepts dropped text (like SimpleText or the NotePad). Pictures can be dragged to the Desktop to create picture clipping files. Other types of data can be dragged using the RawData property.
By default, a DragItem can contain only one row containing a single entry for each data type. Using the AddItem method, you can add more rows to the DragItem allowing multiple entries of the same data type. For example, if you wanted a drag item to contain two separate pictures, you would assign one picture to the Picture property then call the AddItem method to add a row and then assign the second picture to the Picture property.
The RawData and PrivateRawData properties allow you to support drag and drop for other data formats. You specify the data format using a four-character Type, corresponding to a Macintosh resource type. RawData and PrivateRawData return the dragged item as a String. It is up to the control or window that receives the DragItem to manage it. Typically, this will mean that you will have to make API calls or use a plug-in that is designed to handle the data format.
You can also use RawData or PrivateRawData to control internal drag and drop. If you make up a four-character Type (not an existing Macintosh resource type), you can prevent a control from receiving dragged text from other sources. See the example of dragging from one ListBox to another.
For EditFields, drag and drop is supported only if the MultiLine property is True (checked). There is no need to create a DragItem for EditFields as this is handled automatically by REALbasic.
ListBoxes support the dragging of rows automatically if the EnableDrag property of the ListBox is True (checked). Like EditFields, REALbasic creates the DragItem for the ListBox automatically but you must populate the DragItem in the DragRow event handler. See the notes for the ListBox control for more information on dragging from ListBoxes.
The DropWidth and DropHeight properties have no meaning in Win32 and will return 0 unless set using NewDragItem.
Examples
This example shows how to implement dragging the picture in a Canvas control. This example uses the Me keyword to refer to the Canvas control.
Dim d as DragItem
d=NewDragItem( Me.left, Me.top, Me.width, Me.height)
d.picture= Me.Backdrop
d.Drag //Allow the drag
See also the example for ImageWell, which illustrates drag and drop between two ImageWells and PICT files or clippings on the desktop and the ListBox control, which has an example of drag and drop between two ListBoxes.
The following example implements a 'mover' interface in which a user can drag rows from ListBox1 to ListBox2 (and in the reverse direction), but neither ListBox accepts dragged text from other controls or from outside the REALbasic application. It uses PrivateRawData since it also prevents text from being dragged outside the application.
To permit drag and drop in both directions, the two ListBoxes are set up in an identical manner.
Each ListBox has its EnableDrag property set to True. The DragRow event handler is:
Drag.PrivateRawData("text")= Me.List(Row)+ EndOfLine //get the text
Me.RemoveRow(Row)
Return True //allow the drag
To enable each ListBox to accept the dragged text, the following statement appears in its Open event handler:
The DropObject event handler is as follows:
If obj.RawDataAvailable("text") then
Me.AddRow(obj.RawData("text"))
end if
The following example allows the user to drag several text files from the desktop to an EditField. The example places the contents of all the text files in the EditField, appending each file's contents to the Text property of the EditField.
To support several files, the NextItem function is used to determine whether there are any more files remaining to be dropped.
If obj.folderItemAvailable then
Do
textStream=obj. FolderItem.Openastextfile
Me.text= Me.text+textstream.readall+ Chr(13)
loop until not obj.NextItem
End if
The EditField has the line:
in its Open event handler, where "text" is as a File Type of files of Macintosh type TEXT.
See Also
Canvas, EditField, ImageWell, ListBox controls; Picture, FileType, FolderItem classes.